ContentConnect

Content Assets, die in FirstSpirit angelegt werden, bekommen von FirstSpirit eine eindeutige ID. Wird in der Commerce Cloud ein Content Asset mit exakt derselben ID angelegt, wird dieses beim Veröffentlichen von FirstSpirit überschrieben.

Die ContentConnect-Auslieferung enthält drei Module, die auf dem FirstSpirit-Server hinzugefügt werden. Öffnen Sie für die Installation der Module den ServerManager und wählen Sie den Bereich Server-Eigenschaften → Module.

Abbildung 3. Modulverwaltung in den Server-Eigenschaften

Im Hauptpanel ist eine Liste aller auf dem FirstSpirit-Server installierten Module zu sehen. Wählen Sie nach dem Klicken auf Installieren nacheinander zunächst die mitgelieferte contentconnect-fsm-<Versionsnummer>.fsm und anschließend die WebDavDeployment-<Versionsnummer>.fsm sowie die jstl.fsm aus. Bestätigen Sie die Auswahl jeweils mit Öffnen. Nach der erfolgreichen Installation wurden der Liste die Ordner ContentConnect, WebDavDeployment und JSTL hinzugefügt, von denen jeder Alle Rechte erhalten muss.

Die Installation der Module muss anschließend durch die Ergänzung des Apache Commons Codec in der Version 1.8 vervollständigt werden. Dabei handelt es sich um eine Bibliothek, die vom WebDAV-Modul verwendet wird.

Sie benötigen das Archiv commons-codec-1.8-bin.zip, welches Sie unter der folgenden URL herunterladen können: http://commons.apache.org/proper/commons-codec

Extrahieren Sie die Datei an einer beliebigen Stelle innerhalb ihres Dateisystems und separieren Sie das commons-codec-1.8.jar. Diese jar-Datei muss dem FirstSpirit-Server hinzugefügt werden. Öffnen Sie dafür das Verzeichnis Ihrer FirstSpirit-Installation, wechseln Sie in den Unterordner shared → lib und kopieren Sie die jar-Datei hinein.

Um den WebDAV-Server mit https statt http zu verwenden, ist allgemein keine zusätzliche Konfiguration notwendig. Für https wird jedoch im Allgemeinen eine lokale vom Unternehmen verwaltete Zertifizierungsstelle verwendet. Dessen Zertifikat muss inklusive der gesamten Kette bis zum Zertifikat des WebDAV-Servers der JVM des FirstSpirit-Servers zur Verfügung gestellt werden.

Importieren Sie die öffentlichen Root- oder Zwischenzertifikate über das folgende Kommando in eine JKS-Datei und beantworten Sie die Frage, ob dem Zertifikat vertraut werden soll, mit Ja. Dieser Vorgang muss für jedes Zertifikat wiederholt werden.

keytool -import -file cert1.crt -keystore truststore.jks –storepass changeit

Kopieren Sie den erzeugten Trust Store in das Verzeichnis firstspirit5 → conf ihres FirstSpirit-Servers und fügen Sie die folgenden Zeilen der Datei firstspirit5 → conf → fs-wrapper.conf hinzu.

wrapper.java.additional.100=-Djavax.net.ssl.trustStore=conf/truststore.jks
wrapper.java.additional.101=-Djavax.net.ssl.trustStorePassword=changeit
wrapper.java.additional.102=-Djavax.net.ssl.trustStoreType=JKS

Sollte der WebDAV-Server eine wechselseitige SSL-Authentifizierung erwarten, muss über die folgenden Aufrufe zunächst ein Client-Zertifikat erstellt und signiert werden.

openssl genrsa -out private.key 2048
openssl req -new -key private.key -out request.csr

Die Datei request.csr wird an die Zertifizierungsstelle versandt, die mit der Datei cert.crt antwortet. Der private Schlüssel, das öffentliche Zertifikat und das Zertifikat der Zertifizierungsstelle müssen anschließend in einem von der JVM zu lesenden Key Store zusammengefasst werden.

cd firstspirit5/conf
openssl pkcs12 -export -in public.crt -inkey private.key \
-out clientcert.p12 -CAfile authority.crt

Falls die Zertifikatskette aus einem oder mehreren Zwischenzertifikaten besteht, können diese via keytool importiert werden.

keytool -import -file intermediate1.crt -trustcacerts \
-keystore clientcert.p12 -storepass changeit

Der Key Store lässt sich über das Hinzufügen der folgenden Zeilen in die firstspirit5 → conf → fs-wrapper.conf an die JVM des FirstSpirit-Servers übergeben.

wrapper.java.additional.103=-Djavax.net.ssl.keyStore=conf/clientcert.p12
wrapper.java.additional.104=-Djavax.net.ssl.keyStorePassword=changeit
wrapper.java.additional.105=-Djavax.net.ssl.keyStoreType=PKCS12

Für den Einsatz des ContentConnect-Moduls ist eine projektspezifische Konfiguration notwendig. Diese wird über die Projekt-Komponente vorgenommen, die dem verwendeten Projekt hinzuzufügen ist. Öffnen Sie dafür den ServerManager und wählen Sie den Bereich Projekt-Eigenschaften → Projekt-Komponenten.

Abbildung 4. Projekt-Komponenten in den Projekt-Eigenschaften

Im Hauptpanel ist eine Liste aller bereits vorhandenen Projekt-Komponenten zu sehen. Wählen Sie nach dem Klicken auf Hinzufügen die ContentConnect Project Configuration und bestätigen Sie die Auswahl mit OK. Die Projekt-Komponente wird anschließend der Liste im Hauptpanel hinzugefügt und muss anschließend noch konfiguriert werden (vgl. Abbildung Projekt-Komponenten in den Projekt-Eigenschaften). Selektieren Sie dafür den Eintrag in der Liste und öffnen Sie den zugehörigen Konfigurationsdialog über Konfigurieren (vgl. Abbildung Konfigurationsdialog der Projekt-Komponente).

Abbildung 5. Konfigurationsdialog der Projekt-Komponente

<CMS_INPUT_TEXT name="dw_item_id" hidden="yes" useLanguages="no">
  <LANGINFOS>
    <LANGINFO lang="*" label=""/>
  </LANGINFOS>
</CMS_INPUT_TEXT>

Abbildung 6. Kategorie-Report

Da einige Vorlagen JSTL-Code beinhalten, muss vor dem Import der Präsentationskanal des Vorlagensatzes html auf JSP gesetzt werden. Andernfalls sind die Ausgabekanäle der importierten Vorlagen leer. Des Weiteren muss die verwendete Konvertierungsregel die folgende Zeile enthalten: "0x24="$" Ist sie noch nicht vorhanden, kann sie über ServerManager → Server-Eigenschaften → Konvertierungs-Regeln hinzugefügt werden. Abbildung 7. html-Vorlagensatz

Für die Vorschau und den ContentCreator müssen zwei Web-Komponenten hinzugefügt werden. Öffnen Sie hierfür den ServerManager und wählen Sie den Bereich Projekt-Eigenschaften → Web-Komponenten.

Abbildung 8. Web-Komponenten in den Projekt-Eigenschaften

Innerhalb des Hauptpanels sind verschiedene Registerkarten zu sehen, die jeweils eine Liste der bereits vorhandenen Web-Komponenten enthalten. Selektieren Sie nach dem Klicken auf Hinzufügen für die initial ausgewählte Registerkarte Vorschau die ContentConnect Web Resources und FS_JSTL_WebApp und bestätigen Sie die Auswahl mit OK.

Wiederholen Sie diesen Vorgang für den ContentCreator. Die Liste im Hauptpanel wird anschließend für beide Registerkarten um die jeweiligen Web-Komponenten ergänzt (vgl. Abbildung Web-Komponenten in den Projekt-Eigenschaften).

Die Web-Komponenten müssen auf einem aktiven Webserver installiert und danach aktiviert werden. Dieser kann über die Auswahlbox gewählt werden.

Detaillierte Informationen zum Hinzufügen von Web-Komponenten finden Sie in der FirstSpirit Dokumentation für Administratoren.

Für die Funktionalitäten des ContentConnect-Moduls sind einige projektspezifische Informationen erforderlich. Die Informationen werden in den Projekteinstellungen angegeben.

Die Vorlage ist in den Projekt-Eigenschaften auszuwählen und muss dafür im Projekt existieren. Legen Sie sie zunächst an, wenn dies nicht zutreffen sollte. Andernfalls öffnen Sie den ServerManager und wechseln Sie auf den Bereich Projekt-Eigenschaften → Optionen. Selektieren Sie anschließend die Einstellungs-Seite über den entsprechenden Auswahlbutton (vgl. Abbildung Optionen in den Projekt-Eigenschaften). Ein Klick auf den Button OK speichert die vorgenommenen Änderungen.

Abbildung 9. Optionen in den Projekt-Eigenschaften

In der Auslieferung ist die Cartridge int_firstspirit_cms enthalten, die zunächst in die Commerce Cloud übertragen werden muss. Verschiedene Methoden hierzu beschreibt die Commerce Cloud-Dokumentation unter Developing your storefront → Development components → Cartridges.

Anschließend muss die Cartridge allen Sites, die FirstSpirit-Inhalte empfangen sollen, sowie der Business-Manger-Site hinzugefügt werden. Entsprechende Instruktionen finden sich in der Commerce Cloud-Dokumentation unter Getting started → Getting started for developers → Registering your cartridge.

Um die von FirstSpirit generierten Inhalte und Slot-Konfigurationen in die Commerce Cloud zu importieren, ist für jede Site ein Job Schedule in der Commerce Cloud anzulegen. Die Cartridge definiert dazu zwei Job Steps:

Beide besitzen die Pflichtparameter Import File und Import Mode:

Der Job Schedule sollte einen Workflow mit zwei parallelen Flows enthalten. Jeder Flow kann dann einen der beiden oberen Job Steps aufrufen.

Neben der Cartridge enthält die Auslieferung im Verzeichnis metadata außerdem eine Export-Datei eines Job Schedules, der als Referenz genutzt werden kann und die Anlage der verschiedenen Job Schedules vereinfacht.

Nach dem Import sind weitere Anpassung am Job Schedule notwendig. Der Scope beider Job Flows muss auf die richtige Site gesetzt werden. Ebenso ist der Import File-Parameter in beiden Job Steps anzupassen, sodass er den korrekten Pfad enthält.

Die beiden im vorgehenden Kapitel erwähnten Wege zur Referenzierung von Commerce Cloud-Produkten divergieren nur in einem Punkt. Aus diesem Grund wird in diesem Kapitel vorrangig die Umsetzung der FS_LIST skizziert und auf den Unterschied zur Verweisvorlage lediglich an entsprechender Stelle hingewiesen.

Die FS_LIST ist im Beispielprojekt in der Absatzvorlage Featured Products definiert, deren Formular sich außerdem aus den beiden Buttons clickHandler und dropHandler zusammensetzt. Beide Buttons verwenden die Klasse Demandware_ProductDropHandler, die ein Bestandteil des ContentConnect-Moduls ist und die Übertragung eines Commerce Cloud-Produkts regelt.

<FS_LIST name="st_productList" hFill="yes" height="400">
   <DATASOURCE type="inline" useLanguages="yes">
      <LABELS>
         <LABEL lang="*">#item.name</LABEL>
      </LABELS>
      [...]
      <TEMPLATES source="linktemplates">
         <TEMPLATE uid="list_product_link"/>
      </TEMPLATES>
   </DATASOURCE>
</FS_LIST>

<FS_BUTTON
    name="dropHandler"
    icon="media:drop_zone_product"
    noBreak="yes"
    onDrop="class:DemandwareConnect_ProductDropHandler"
    style="link">

   <DROPTYPES>
        <MIME type="application/x-java-serialized-object"
            classname="com.espirit.moddev.demandware.products.Product"/>
   </DROPTYPES>
   <PARAMS>
      <PARAM name="list">#field.st_productList</PARAM>
      <PARAM name="id">id</PARAM>
      <PARAM name="name">name</PARAM>
   </PARAMS>
</FS_BUTTON>

<FS_BUTTON name="clickHandler" onClick="class:DemandwareConnect_ProductDropHandler">
   <LANGINFOS>
      <LANGINFO lang="*" label="Add product from selection"/>
   </LANGINFOS>
   <PARAMS>
      <PARAM name="list">#field.st_productList</PARAM>
      <PARAM name="id">id</PARAM>
      <PARAM name="name">name</PARAM>
   </PARAMS>
</FS_BUTTON>

Beide Buttons werden auch in der Verweisvorlage Product Hot Spot verwendet. Dort müssen die Parameter der Buttons jedoch anders definiert werden:

<PARAMS>
   <PARAM name="id">#field.id</PARAM>
   <PARAM name="name">#field.name</PARAM>
   <PARAM name="variationAttributes">#field.variationAttributes</PARAM>
</PARAMS>

Dieser Unterschied basiert auf der Tatsache, dass die Felder id und name im Formular der Verweisvorlage parallel zu den beiden Buttons platziert sind. Sie werden daher über den vorangestellten Ausdruck #field direkt angesprochen. In der Absatzvorlage Featured Products sind die Buttons hingegen parallel zur FS_LIST angeordnet und die Felder id und name in der von ihr referenzierten Verweisvorlage list_product_link enthalten.

Die beiden Buttons im Formular der Verweisvorlage besitzen außerdem den Parameter variationAttributes, der ein verstecktes Textfeld anspricht. Dieses wird für die Persistierung der einem Produkt zugehörigen spezifischen Variationsattribute verwendet. Da die Absatzvorlage Featured Products lediglich der Ausgabe allgemeiner Produktinformationen dient, benötigen die Buttons in ihrem Formular diesen Parameter nicht.

Die Buttons ermöglichen den Redakteuren eine schnelle und unkomplizierte Referenzierung der Commerce Cloud-Produkte in FirstSpirit, ohne dass dabei der Client verlassen werden muss. Andernfalls müssten die Produktinformationen in der Commerce Cloud ermittelt und dann manuell übertragen werden. Pro FirstSpirit-Client wird immer nur einer der beiden Buttons angezeigt.

Abbildung 13. DropHandler

Abbildung 14. ClickHandler

Wie bereits zuvor erwähnt, sind die Buttons spezifisch für jeweils einen der beiden FirstSpirit-Clients. Sie müssen daher im entsprechend anderen Client ausgeblendet werden. Diese Anforderung wird über die Regeln gesteuert, die sowohl in der genannten Absatz- als auch in der Verweisvorlage definiert sind.

Die erste Abfrage aktiviert den Button clickHandler, wenn ein im Report dargestelltes Commerce Cloud-Produkt in die Zwischenablage kopiert wurde.
Die letzten beiden Abfragen prüfen, ob der aktuelle Redakteur sich im ContentCreator befindet. Befindet er sich im SiteArchitect, wird der Button clickHandler eingeblendet. Andernfalls ist der Button dropHandler sichtbar.

<RULES>
   <ON_EVENT>
      <SCHEDULE service="DemandwareConnect_ClipboardFilled" id="product_link_clipboard_check">
         <!-- Some FS versions complain about an invalid rule definition without a parameter -->
         <PARAM name="dummy">
            <TEXT>dummy</TEXT>
         </PARAM>
      </SCHEDULE>
      <DO>
         <PROPERTY source="clickHandler" name="EDITABLE" />
      </DO>
   </ON_EVENT>

   <ON_EVENT>
      <WITH>
         <NOT>
            <PROPERTY source="#global" name="WEB"/>
         </NOT>
      </WITH>
      <DO>
         <PROPERTY source="clickHandler" name="VISIBLE"/>
      </DO>
   </ON_EVENT>

   <ON_EVENT>
      <WITH>
         <PROPERTY source="#global" name="WEB"/>
      </WITH>
      <DO>
         <PROPERTY source="dropHandler" name="VISIBLE"/>
      </DO>
   </ON_EVENT>
</RULES>

Existiert im Formular der verwendeten Vorlage das Textfeld variationAttributes, öffnet sich bei der Referenzierung eines Master-Produkts über einen der beiden Buttons ein zusätzlicher Dialog. Dieser stellt alle dem ausgewählten Produkt zugehörigen Variationsattribute dar, über die sich die Produktauswahl spezifizieren lässt.(vgl. Abbildung Spezifikation eines Produkts).

Ergibt sich durch die Spezifikation die Definition einer bestimmten Produktvariante, werden in den Feldern id und name der Verweisvorlage bzw. der FS_LIST die Informationen dieser Variante gespeichert. Andernfalls werden die Id und der Name des Master-Produkts übernommen und die im Dialog definierten Variationsattribute in Form eines JSONs im versteckten Feld variationAttributes persistiert.

Abbildung 15. Spezifikation eines Produkts

Für die Darstellung referenzierter Produkte in der Vorschau können mithilfe des Produkt-Managers weitere Produktinformationen abgefragt werden. Der Produkt-Manager wird in den Projekteinstellungen initialisiert, deren Vorlage während der Konfiguration der Projektkomponente in das Projekt importiert wurde. Je nach Anwendungsfall können mit ihm sowohl spezifische Variationsattribute als auch allgemeine Produktinformationen ermittelt werden.

Dieses Kapitel skizziert die Idee einer Liste "ähnlicher Produkte". In diesem Fall werden lediglich allgemeine Informationen, wie beispielsweise der Name und der Preis eines Produkts, benötigt. Spezifische Attribute sind hingegen an dieser Stelle nicht von Bedeutung.

Das nachfolgende Beispiel basiert auf der Annahme, dass für die Referenzierung der Produkte die zuvor beschriebene FS_LIST verwendet wurde. Es kann anhand der Absatzvorlage Featured Products nachvollzogen werden.

Jedes in der FS_LIST referenzierte Produkt wird beim Durchlaufen der FOR-Schleife zunächst über den Produkt-Manager geladen. Befindet sich der Redakteur in der Vorschau, werden anschließend durch die Verwendung einfacher Getter-Methoden das Produktbild, der Name und der Preis ermittelt und dargestellt.

$CMS_FOR(for_product,st_productList)$
   $CMS_IF(!for_product.id.isEmpty)$
      $CMS_SET(set_product,ps_productManager.loadProduct(for_product.id))$
      [...]
      $CMS_IF(!#global.preview)$
         [...]
      $CMS_ELSE$
         $-- FirstSpirit Preview --$
         <li>
            <div class="product-tile">
               <div class="product-image">
                  <a class="thumb-link" href="#" title="">
                     <img src="$CMS_VALUE(set_product.getImageUrl(set_width,set_height))$">
                  </a>
               </div>
               <div class="product-name">
                  <a class="name-link" href="#">
                     $CMS_VALUE(set_product.getName())$
                  </a>
                  <div class="product-price">
                     <span class="price-sales">
                        $CMS_VALUE(set_product.getCurrency())$
                        $CMS_VALUE(set_product.getPrice().format("0.00"))$
                     </span>
                  </div>
               </div>
               [...]
            </div>
         </li>
      $CMS_END_IF$
   $CMS_END_IF$
$CMS_END_FOR$

Im Gegensatz zur im vorhergehenden Kapitel beschriebenen Darstellung allgemeiner Daten können mithilfe des Produkt-Managers auch spezifische Produktinformationen abgefragt werden.

Dieses Kapitel beschreibt die Idee sogenannter "Hot Spots". Dabei handelt es sich um gezielte Verweise auf spezifische Produktvarianten. Für sie werden die der jeweiligen Variante zugehörigen Variationsattribute benötigt. Die allgemeinen Informationen sind hingegen an dieser Stelle nicht von Bedeutung.

Das nachfolgende Beispiel basiert auf der Annahme, dass für die Referenzierung eines Produkts die zuvor beschriebene Verweisvorlage Product Hot Spot verwendet wurde. Anhand der Vorlage lässt sich das Beispiel nachvollziehen.

Für ein über die Verweisvorlage referenziertes Produkt wird zunächst ein Link auf die Commerce Cloud-Pipeline LinkProduct generiert und diesem die Id des Produkts übergeben. Handelt es sich bereits um eine spezifische Variante, ist das Feld variationAttributes leer. Andernfalls lädt der Produktmanager nacheinander alle in dem Feld gespeicherten Variationsattribute, die bei der Referenzierung des Produkts definiert wurden. Für jedes dieser Attribute wird dessen Id (z.B. "Farbe") sowie der gewählten Wert (z.B. "gelb") ermittelt und aus ihnen eine per "&"-Zeichen separierte Liste erzeugt. Der initial erzeugte Link auf die Commerce Cloud-Pipeline LinkProduct wird abschließend um diese Liste ergänzt.

$CMS_IF(!#global.preview)$
   $CMS_SET(set_lt_link,"$link-product:pid="+id+"$&")$

   $CMS_IF(!variationAttributes.isEmpty)$
      $CMS_SET(set_attributes, ps_productManager.convertVariationValuesJSON2List(variationAttributes).map(x -> x.key + "=" + x.value).toString("&"))
      $CMS_SET(set_lt_link, set_lt_link + set_attributes)$
   $CMS_END_IF$
$CMS_END_IF$

<a href="$CMS_VALUE(set_lt_link)$"> ... </a>

Objekte, die noch keine Detailseite besitzen, werden im Report durch ein graues Icon markiert (vgl. Abbildung Anlegen einer Detailseite). Wurde in der Projekt-Komponente eine Seitenvorlage definiert, erscheint beim Überfahren eines solchen Objekts die Schaltfläche .

Abbildung 16. Anlegen einer Detailseite

Per Klick auf diese Schaltfläche öffnet sich ein zweigeteilter Dialog, mit dem sich für das entsprechende Objekt eine Detailseite anlegen lässt.

Der obere Teil des Dialogs ist der Struktur-Auswahl-Bereich, der automatisch eingefügt wird und damit immer gleich ist. Er stellt dem Redakteur die Möglichkeit zur Verfügung, innerhalb der Struktur die Menüebene auszuwählen, in der die neue Detailseite erzeugt wird. Potentiell ist die entsprechende Eingabekomponente schon vorbelegt. Dann wurde im Konfigurationsdialog der Projekt-Komponente bereits ein Struktur-Ordner definiert. Es steht dem Redakteur jedoch frei, diese Auswahl anzupassen.

Im Gegensatz zum Struktur-Auswahl-Bereich ist der untere Formular-Bereich immer projektspezifisch. Er zeigt das Formular der in der Projekt-Komponente angegebenen Seitenvorlage. In ihm gelten außerdem die in der Vorlage definierten Regeln.

Die folgende Abbildung zeigt einen beispielhaften Dialog:

Abbildung 17. Dialog zum Anlegen einer Detailseite

Ein Klick auf Anlegen erzeugt die Seitenreferenz der Detailseite in der zuvor gewählten Menüebene. Die zugehörige Seite wird in einem festem Ordner in der Inhalte-Verwaltung erstellt.

Ist innerhalb der Projekt-Komponente außerdem ein Skript angegeben, so wird dieses vor und nach der Erzeugung der Detailseite ausgeführt.

Diesem Skript werden die folgenden Parameter übergeben:

Nach der vollständigen Erzeugung der Detailseite und dem Ausführen des Skriptes wird die neu erstellte Seite aufgerufen.

Objekte, für die bereits eine Detailseite existiert, werden im Report durch einen grünes Icon markiert (vgl. Abbildung Produkt mit Detailseite). Sie erhalten beim Überfahren die Schaltfläche , mit der die zugehörige Detailseite aufgerufen werden kann.

Abbildung 18. Produkt mit Detailseite

Besitzt ein Objekt eine Detailseite, für die jedoch die Seitenreferenz oder die zugrunde liegende Seite nicht gefunden werden kann, so wird das Objekt im Report mit einem rotes Icon markiert (vgl. Abbildung Objekt mit Defekt). Solche Objekte erhalten beim Überfahren die Schaltfläche . Ein Klick auf diese Schaltfläche öffnet einen Dialog, der weitere Informationen bereit hält.

Abbildung 19. Objekt mit Defekt

Der JavaScript Controller soll ein übergebenes Content Asset auslesen und mit Hilfe einer Velocity Seitenvorlage darstellen. Diese Aufgabe lässt sich in vier grundlegende Schritte unterteilen:

Diese Schritte sowie ihre Implementierung werden im Folgenden beschrieben.

Der JavaScript Controller enthält eine öffentliche Methode Show, die als Einstiegspunkt zum Rendern von Content Assets dient und die Klassen dw.template.Velocity und dw.content.ContentMgr aus der Commerce Cloud Script API verwendet. Das Grundgerüst des Controllers sieht somit wie folgt aus:

"use strict";

var contentManager = require("dw/content/ContentMgr"); ❶
var velocity = require('dw/template/Velocity'); ❷

exports.Show = function() { ❸
    // ...
};

exports.Show.public = true; ❹

Zum Auslesen des Content Assets wird zunächst der HTTP-GET-Parameter cid ermittelt, dessen Wert dann dem ContentMgr übergeben wird, um das Content Asset auszulesen. Falls ein Redakteur eine neue Seite anlegt, ist der Commerce Cloud noch kein entsprechendes Content Asset bekannt. Um in FirstSpirit trotzdem eine Vorschau für die neue Seite zu ermöglichen, wird in diesem Fall ein temporäres Objekt anstelle des Content Assets verwendet, das ein leeres Asset imitiert.

var contentAssetId = request.getHttpParameterMap().get("cid"); ❶
var contentAsset = contentManager.getContent(contentAssetId) ❷
                || { custom: { body: "" }, template: "welcome_page.vs" }; ❸

Anschließend wird ein Objekt mit dem Namen global definiert. Mit diesem Objekt wird der Velocity Engine eine spezialisierte API bereitgestellt, deren Funktionen und Eigenschaften in der verarbeiteten Velocity Seitenvorlage nutzbar sind. Struktur und Inhalt dieses Objektes müssen projekt- und seitenspezifisch definiert und implementiert werden. Denkbar sind zum Beispiel Funktionen, die unter einem sprechenden Namen verschiedene Widgets einbinden.

var global = {
    ❶
};

Die Eigenschaft body speichert den Inhalt des Content Assets und muss beim hier beschriebenen Ansatz immer in irgendeiner Form im global-Objekt vorhanden sein. Da der Inhalt des Assets selbst Velocity Code enthalten kann, wird dieser zunächst über die Velocity Engine interpretiert und das Ergebnis in body gespeichert. Beim Rendern des Content Assets kann der Velocity Engine ein separates Parameter-Objekt zur Verfügung gestellt werden. Genauso ist es aber möglich, global wieder zu verwenden.

function render(content, parameters) {
    var writer = new dw.io.StringWriter();
    velocity.render(content, parameters, writer)
    return writer.toString();
}

// ...

global.body = render(contentAsset.custom.body, global);

Abschließend wird die am Content Asset hinterlegte Velocity Seitenvorlage gerendert und das Ergebnis dem Aufrufer angezeigt. Als Parameter-Objekt wird das zuvor erstellte Objekt global übergeben.

velocity.renderTemplate(contentAsset.template, global);

Die Commerce Cloud bietet viele Möglichkeiten Seiten zu cachen und so schnelle Antwortzeiten zu gewährleisten. Falls eine Seite kunden- oder sessionabhängige Informationen enthält und das Caching nicht richtig konfiguriert ist, kann es jedoch schnell zu unerwarteten Ergebnissen kommen.

Aufbauend auf den Erläuterungen des Kapitels JavaScript Controller wird im Folgenden anhand eines konkreteren Beispiels ein Ansatz erläutert, der ein korrektes Ergebnis sicherstellt.

Anzuzeigen ist eine aus vier Blöcken bestehende Seite. Bei diesen Blöcken handelt es sich um

Diese Blöcke bieten unterschiedliches Potential gecacht zu werden.

Der Banner ist lediglich abhängig vom Geschlecht des Kunden. Das heißt, dass alle Kunden in zwei Gruppen unterteilt werden können: weibliche und männliche Kunden. Innerhalb einer Gruppe ist der Inhalt für alle Kunden identisch, wohingegen Kunden verschiedener Gruppen verschiedene Inhalte sehen. Aus diesem Grund kann der Inhalt für beide Gruppen getrennt und für einen längeren Zeitraum gecacht werden. Allerdings muss bei jedem Seitenaufruf das Geschlecht des Kunden ausgewertet werden, um den richtigen Cache anzusprechen.

Der Header enthält Informationen, die abhängig von jedem einzelnen Kunden sind, wie zum Beispiel seinen Namen. Für diese Komponente muss das Caching also pro Kunde erfolgen. Die Gültigkeit des Caches kann dabei kurz gehalten werden, da die kundenspezifischen Inhalte im Vergleich zu allgemeinen Inhalten seltener und für kürzere Zeit benötigt werden.

Der Footer wird nicht personalisiert und kann deshalb für alle Kunden und für einen langen Zeitraum gecacht werden.

Der Inhalt des Content Assets kann selbst Velocity Code enthalten, weshalb er getrennt betrachtet werden muss. Allerdings gelten für ihn die gleichen Überlegungen, weshalb auf ihn nicht weiter eingegangen wird.

Die einzelnen Komponenten stellen unterschiedliche Anforderungen an das Caching, weshalb es sinnvoll ist, jede in einem separaten Widget zu kapseln, sodass für jedes das Caching einzeln gesteuert werden kann. Da das Commerce Cloud-Caching auf URLs basiert und einem Widget Parameter über seine Anfrage-URL übergeben werden, kann das Caching der Widgets über Parameter gesteuert werden. Für das Banner-Widget ist beispielsweise ein Parameter isFemale sinnvoll, der einen boolschen Wert enthält. Es sind also zwei gültige URLs denkbar, was zu zwei Caches für das Widget führt: Einer für weibliche und einer für männliche Kunden. Genauso kann für das Header-Widget ein Parameter id definiert werden, in dem die Id des Kunden abgelegt wird. Dadurch wird der spezifische Inhalt für jeden Kunden einzeln vorgehalten.

Die einzelnen Widgets werden dann beim Rendern der initial aufgerufenen Seite über Remote Includes integriert. Das vollständig zusammengesetzte Ergebnis dieser Seite kann ebenfalls gecacht werden, wodurch die Einstellungen der einzelnen Widgets ausgehebelt werden würden und es doch zu unerwarteten Ergebnissen käme. Deshalb ist es wichtig, diese Antwort nicht zu cachen. Folglich wird die angeforderte Seite also bei jedem Aufruf neu zusammengebaut, die einzelnen Komponenten jedoch durch ihr individuelles Caching wiederverwendet.

Realisiert wird dies über den JavaScript Controller und das Parameter-Objekt global, welches er der Velocity Engine bereitstellt. Das global-Objekt enthält in diesem Beispiel die parameterlosen Funktionen include.banner(), include.header() und include.footer(), die an den passenden Stellen in der Velocity Seitenvorlage aufgerufen werden. Des Weiteren beinhaltet es wie bisher die Eigenschaft body, die den Inhalt des Content Assets speichert. Innerhalb der include-Funktionen werden die jeweiligen Widgets über passend parametrisierte Velocity.remoteInclude-Aufrufe in die Seite integriert. Der initial aufgerufene JavaScript Controller, der das global-Objekt erzeugt und das Rendern der Velocity Seitenvorlage anstößt, darf wie angesprochen nicht gecacht werden, damit er bei jedem Seitenaufruf ausgeführt wird und die Caching-Einstellungen der einzelnen Widgets nicht umgangen werden. Dies ist das Standard-Verhalten, weshalb kein zusätzlicher Code notwendig ist.

Das Zusammenspiel zwischen Velocity Seitenvorlage, Parameter-Objekt und Widgets ist in Abbildung Caching Beispiel dargestellt.

Abbildung 27. Caching Beispiel

Die verwendete Velocity Seitenvorlage wird in FirstSpirit gepflegt und an die Commerce Cloud übertragen. Dazu ist in FirstSpirit zunächst eine Seitenvorlage anzulegen, deren Ausgabekanal für dieses Beispiel folgenden Inhalt hat:

<!DOCTYPE html>
<html>
    <body>
        <!-- CMS-PREVIEW-CONTENT-START --> ❶
        $body ❷
        <!-- CMS-PREVIEW-CONTENT-END --> ❸
    </body>
</html>

Auf Basis dieser neuen Seitenvorlage muss anschließend jeweils genau eine Seite und eine Seitenreferenz angelegt werden. Dabei sollte zumindest die Seitenreferenz in einem separaten Ordner auf der obersten Ebene der Struktur platziert werden, um die spätere Übertragung der Velocity Seitenvorlage zur Commerce Cloud zu vereinfachen.

Die Velocity Seitenvorlage wird nach der Freigabe der in Kapitel Velocity Seitenvorlage erzeugten Objekte von FirstSpirit generiert. Zur Übertragung zur Commerce Cloud muss der in Kapitel Deployment-Auftrag beschriebene Auftrag um ein weiteres WebDAV-Deployment erweitert werden. Dies geschieht am einfachsten, indem eine Kopie der Aktion aus Kapitel WebDAV-Deployment erzeugt und angepasst wird. Folgende Parameter sind zu überarbeiten:

Alle sonstigen Parameter können übernommen werden.

Da dieser Ansatz zur Nutzung der Content Integration API weiterhin Content Assets erzeugt, gelten für Seitenvorlagen für redaktionelle Inhalte alle Überlegungen aus Kapitel Seitenvorlage. Es sind lediglich zwei spezifische Anpassungen vorzunehmen.

Zum einen muss das Attribut template am Content Asset gepflegt sein, da dieses im JavaScript Controller herangezogen wird, um die richtige Velocity Seitenvorlage zu ermitteln.

Des Weiteren muss für alle neuen Seitenvorlagen ein neuer Page Type definiert werden, damit die für die Vorschau generierte URL den richtigen JavaScript Controller-Aufruf enthält. Konkret muss also die Variable pt_dwre_previewType auf einen neuen Wert gesetzt werden. Für das Beispiel dieses Kapitels wird dafür content benutzt.

Die in der Auslieferung enthaltene Formatvorlage Create Preview URL muss um einen weiteren Fall erweitert werden, damit die Vorschau für Seiten, die die Content Integration API nutzen, korrekt funktioniert.

Der verwendete Vergleichswert hängt vom neuen Page Type ab, der in der Seitenvorlage aus Kapitel Seitenvorlage für redaktionelle Inhalte verwendet wurde.

Entsprechend hängt die aufgerufene URL vom Namen des Controllers, der aufzurufenden Methode sowie der benötigten Parameter ab (siehe Kapitel JavaScript Controller).

In diesem Beispiel wäre der neue Eintrag in der Vorlage Create Preview URL also:

$CMS_CASE("content")$Content-Show?cid=$CMS_VALUE(pageId)$

Eingangs wurde bereits darauf hingewiesen, dass mit der Content Integration API Redakteuren mehr Möglichkeiten bei der Gestaltung einer Seite gegeben werden können. Visuelle Komponenten, die ein Redakteur auf einer Seite platzieren und anordnen können soll, werden Commerce Cloud-seitig am besten als Widget implementiert. Auf Seiten FirstSpirits bietet es sich dann an, für jedes Widget eine Absatzvorlage zu definieren.

Innerhalb des Ausgabekanals einer solchen Vorlage muss zwischen Vorschau und Nicht-Vorschau unterschieden werden. Für die Vorschau wird die Anfrage-URL des Widgets bestimmt. Diese URL wird dann dem Skript include_html übergeben, welches Teil der Auslieferung ist. In diesem Skript wird die URL aufgerufen und das Ergebnis in die generierte Seite eingefügt.

Für die Generierung des Content Assets wird stattdessen lediglich ein Velocity-Aufruf erzeugt. Welche Funktion aufgerufen wird und welche Parameter sie erwartet, hängt vom Parameter-Objekt ab, welches im JavaScript Controller definiert und der Velocity Engine beim Rendern des Content Assets übergeben wird.

Ein generalisiertes Beispiel ist in Listing Ausgabekanal einer Absatzvorlage eines Widgets zu sehen. Zum Einbetten des Widgets wird eine allgemeine Funktion verwendet, die den Namen des Widgets und die benötigten Parameter entgegennimmt.

Ausgabekanal einer Absatzvorlage eines Widgets. 

$CMS_IF(#global.isPreview)$
    <div $CMS_VALUE(editorId())$ >
        $CMS_SET(set_includeURL, ps_dwProtocol + ps_dwInstance + ".demandware.net/on/demandware.store/")$
        $CMS_SET(set_includeURL, set_includeURL + "Sites-" + ps_dwSiteId + "-Site/")$
        $CMS_SET(set_includeURL, set_includeURL + #global.language.abbreviation + "/")$ ❶
        $CMS_SET(set_includeURL, set_includeURL + <ACTION> + <PARAMETER>)$

        $CMS_RENDER(script:"include_html", includeURL:set_includeURL.toString())$
    </div>
$CMS_ELSE$
    $include.widget("<ACTION>", <PARAMETER>)
$CMS_END_IF$